<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
    <title>Chapter 15: Using SSL</title>
    <link rel="stylesheet" type="text/css" href="../css/common.css" />
    <link rel="stylesheet" type="text/css" href="../css/screen.css" media="screen" />
    <link rel="stylesheet" type="text/css" href="../css/_print.css" media="print" />
    <link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen" />    

  </head>
  <body onload="prettyPrint(); decorate();">
    <script type="text/javascript">prefix='../';</script>
    <script type="text/javascript" src="../js/prettify.js"></script>
    <script type="text/javascript" src="../templates/header.js"></script>
    <script type="text/javascript" src="../js/dsl.js"></script>
    <script type="text/javascript" src="../js/jquery-min.js"></script>
    <script type="text/javascript" src="../js/decorator.js"></script>
    <div id="left">      
      <noscript>Please turn on Javascript to view this menu</noscript>
      <script src="../templates/left.js" type="text/javascript"></script>
    </div>    
    <div id="right">
      <script src="menu.js" type="text/javascript"></script>
    </div>
    <div id="content">    

      <h1>Chapter 15: Using SSL</h1>


    <a href="usingSSL_ja.html">&#x548C;&#x8A33; (Japanese translation)</a>
      
      <div class="quote">

        <p><em>The whole difference between construction and creation is 
        exactly this: that a thing constructed can only be loved after it 
        is constructed; but a thing created is loved before it exists.</em></p>
        <p>&mdash;CHARLES DICKENS</p>
      </div>


      <script src="../templates/creative.js" type="text/javascript"></script>
      <!-- script src="../templates/setup.js" type="text/javascript"></script -->

      <p>Logback supports the use of the Secure Sockets Layer 
         (SSL) when delivering log events from a socket-based appender
         to a remote receiver.  When using an SSL-enabled appender and  
         corresponding receiver, serialized logging events are delivered 
         over a secure channel.
      </p>
      
      <h2 class="doAnchor">SSL and Component Roles</h2>
      
      <p>Logback components such as appenders and receivers may act in
      either the server role or the client role, with respect to network
      connection initiation. When acting in the server role, a logback
      component passively listens for connections from remote client
      components.  Conversely, a component acting in the client role 
      initiates a connection to remote server component.  For example, 
      an appender acting in the <em>client</em> role connects to a 
      receiver acting in the <em>server</em> role.  Or a receiver
      acting in the <em>client</em> role connects to an appender
      acting in the <em>server</em> role.</p>
      
      <p>The roles of the components are generally determined by the
      component type.  For example, an <code>SSLServerSocketAppender</code>
      is an appender component that acts in the server role, while an
      <code>SSLSocketAppender</code> is an appender component that acts
      in the client role.  Thus the developer or application administrator 
      can configure Logback components to support the desired direction
      of network connection initiation.</p>
      
      <p>The direction of connection initiation is significant in the 
      context of SSL, because in SSL a server component must possess an
      X.509 credential to identify itself to connecting clients.  A
      client component, when connecting to the server, uses the server's
      certificate to validate that the server is trusted.  The
      developer or application administrator must be aware of the 
      roles of Logback components, so as to properly configure the
      server's key store (containing the server's X.509 credential) 
      and the client's trust store (containing self-signed 
      root certificates used when validating server trust).</p>
      
      <p>When SSL is configured for <em>mutual authentication</em>, then
      both the server component and the client component must possess
      valid X.509 credentials whose trust can be asserted by their 
      respective peer.  Mutual authentication is configured in the
      server component, therefore the developer or application 
      administrator must be aware of which components are acting in 
      the server role.</p>
      
      <p>In this chapter, we use the term <em>server component</em>
      or simply <em>server</em> to refer to a Logback component such
      as an appender or receiver that is acting in the server role.  We
      use the term <em>client component</em> or simply <em>client</em>
      to refer to a component that is acting in the client role.
            
      <h2 class="doAnchor">SSL and X.509 Certificates</h2>
      
      <p>In order to use SSL-enabled Logback components, you will need an
         X.509 credential (a private key, corresponding certificate,
         and CA certification chain) to identify your components
         that act as SSL servers.  If you wish to use mutual authentication, 
         you will also need credentials for your components that 
         act as SSL clients.
      </p>      
      <p>While you can use a credential issued by a commercial
         certification authority (CA), you can also use a certificate issued
         from your own internal CA or even a self-signed certificate.  The
         following is all that is required:
      </p> 
      <ol>
        <li>The server component must be configured 
            with a key store containing the server's private key, 
            corresponding certificate, and CA certification chain
             (if not using a self-signed certificate).
        </li>
        <li>The client component must be configured 
            with a trust store containing trusted root CA 
            certificate(s) or the server's self-signed root certificate.
        </li>
      </ol>
          
      <h2 class="doAnchor">Configuring Logback Components for SSL</h2>
      <p>The Java Secure Sockets Extension (JSSE) and Java Cryptography 
         Architecture (JCA) which is used to implement Logback's SSL
         support has many configurable options, and a pluggable provider
         framework that allows the built-in SSL and cryptographic
         capabilities of the platform to be replaced or augmented.
         SSL-enabled Logback components provide the ability to fully specify 
         all of the configurable aspects of the SSL engine and cryptographic 
         providers, to meet your unique security needs.
      </p>
      
      <h3>Basic SSL Configuration using JSSE System Properties</h3>
      <p>Fortunately, nearly all of the configurable SSL properties for
         SSL-enabled Logback components have reasonable defaults.  In 
         most cases all that is needed is the configuration of some JSSE 
         system properties.
      </p>
      
      <p>The remainder of this section describes the specific JSSE
         properties that are needed in most environments. See 
         <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#InstallationAndCustomization">
         Customizing JSSE</a> in the <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html">
         JSSE Reference Guide</a> for more information on setting JSSE
         system properties to customize JSSE.      
      </p>

      <p>If you're using any of Logback's SSL-enabled appender or receiver
         components that act in the server role (e.g. 
         <code>SSLServerSocketReceiver</code>, 
         <code>SSLServerSocketAppender</code>,
         or <code>SimpleSSLSocketServer</code>) you'll need to configure 
         JSSE system properties that provide the location, type, and 
         password of the key store containing a private key and 
         certificate.
      </p>
      
      <h4><a name="basicConfig.keyStore"></a>
          System Properties for Server Key Store Configuration</h4>
      <table class="bodyTable striped">
        <tr>
          <th>Property Name</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><code>javax.net.ssl.keyStore</code></td>
          <td>Specifies a filesystem path to the file containing your
              server components' private key and certificate.</td>
        </tr>
        <tr>
          <td><code>javax.net.ssl.keyStoreType</code></td>
          <td>Specifies the key store type.  If this property is not
              specified, the platform's default type (JKS) is assumed.
          </td>
        </tr>
        <tr>
          <td><code>javax.net.ssl.keyStorePassword</code></td>
          <td>Specifies the password needed to access the key store.
          </td>
        </tr>
      </table>

      <p>See <a href="#Examples">Examples</a> below for examples of
         setting these system properties when starting an application
         that uses Logback's SSL-enabled server components.
      </p>
         
      <p>If your server component is using a certificate 
         that was signed by a commercial certification authority (CA), 
         <strong>you probably don't need to provide <em>any</em> SSL 
         configuration in your applications that use SSL-enabled client 
         components</strong>.  When using a commercially-signed 
         certificate for your server  component, simply setting the 
         system key store properties for JVM that runs the server 
         component is usually all that is needed.
      </p>
               
      <p>If you are using either a self-signed server certificate
         or your server certificate was signed by a
         certification authority (CA) that is not among those whose root
         certificates are in the Java platform's default trust store
         (e.g. when your organization has its own internal certification
         authority), you will need to configure the JSSE system
         properties that provide the location, type, and password of the
         trust store containing your server's certificate or trusted
         root certificates for the certification authority (CA) that
         signed your server's certificate.  <strong>These properties will 
         need to be set in each application that utilizes an SSL-enabled
         client component</strong>.
      </p>
        
      <h4><a name="basicConfig.trustStore"></a>
          System Properties for Client Trust Store Configuration</h4>
      <table class="bodyTable striped">
        <tr>
          <th>Property Name</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><code>javax.net.ssl.trustStore</code></td>
          <td>Specifies a filesystem path to the file containing your
              server component's certificate or trusted root
              certificate(s) for the certification authority (CA) that
              signed the server certificate.</td>
        </tr>
        <tr>
          <td><code>javax.net.ssl.trustStoreType</code></td>
          <td>Specifies the trust store type.  If this property is not
              specified, the platform's default type (JKS) is assumed.
          </td>
        </tr>
        <tr>
          <td><code>javax.net.ssl.trustStorePassword</code></td>
          <td>Specifies the password needed to access the trust store.
          </td>
        </tr>
      </table>

      <p>See <a href="#Examples">Examples</a> below for examples of
         setting these system properties when starting an application 
         that utilizes Logback's SSL-enabled client components.
      </p>         
            
      <h3 class="doAnchor"><a name="SSLConfiguration"></a>
         Advanced SSL Configuration</h3>
      <p>In certain situations, the basic SSL configuration using 
         JSSE system properties is not adequate.  For example, if you
         are using the <code>SSLServerSocketReceiver</code> component in a web
         application, you may wish to use a different credential to
         identify your logging server for your remote logging clients
         than the credential that your web server uses to identify
         itself to web clients.  You might wish to use SSL client
         authentication on your logging server to ensure that only
         authentic and authorized remote loggers can connect. Or perhaps
         your organization has strict policies regarding the SSL
         protocols and cipher suites that may be utilized on the
         organization's network.  For any of these needs, you will need
         to make use of Logback's advanced configuration options for SSL.
      </p>
      <p>When configuring a Logback component that supports SSL, you 
         specify the SSL configuration using the <code>ssl</code> 
         property in the configuration of the component.          
      </p>      
      <p>For example, if you wish to use <code>SSLServerSocketReceiver</code>
         and configure the key store properties for your logging 
         server's credential, you could use a configuration such as the 
         following.
      </p>

      <span class="asGroovy" onclick="return asGroovy('logback-ssl-serverKeyStore');">View as .groovy</span>
      <pre id="logback-ssl-serverKeyStore" class="prettyprint source">&lt;configuration>

  &lt;appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    &lt;encoder>
      &lt;pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n&lt;/pattern>
    &lt;/encoder>
  &lt;/appender>
  
  &lt;root level="debug">
    &lt;appender-ref ref="CONSOLE" />
  &lt;/root>

  &lt;receiver class="ch.qos.logback.classic.net.server.SSLServerSocketReceiver">
    &lt;ssl>
      &lt;keyStore>
        &lt;location>classpath:/logging-server-keystore.jks&lt;/location>
        &lt;password>changeit&lt;/password>
      &lt;/keyStore>
    &lt;/ssl>
  &lt;/receiver> 

&lt;/configuration></pre>

      <p>This configuration specifies the location of the key store
         as <em>logging-server-keystore.jks</em> at the root of
         the application's classpath.  You could alternatively 
         specify a <code>file:</code> URL to identify the location of
         the key store.
      </p>
      <p>If you wanted to use <code>SSLSocketAppender</code> in your
         application's Logback configuration, but did not want to change
         the application's default trust store using the JSSE
         <code>javax.net.ssl.trustStore</code> property, you could 
         configure the appender as follows.
      </p>          

      <span class="asGroovy" onclick="return asGroovy('logback-ssl-clientTrustStore');">View as .groovy</span>
      <pre id="logback-ssl-clientTrustStore" class="prettyprint source">&lt;configuration>
  &lt;appender name="SOCKET" class="ch.qos.logback.classic.net.SSLSocketAppender">
    &lt;ssl>
      &lt;trustStore>
        &lt;location>classpath:/logging-server-truststore.jks&lt;/location>
        &lt;password>changeit&lt;/password>
      &lt;/trustStore>
    &lt;/ssl>
  &lt;/appender>
  
  &lt;root level="debug">
    &lt;appender-ref ref="SOCKET" />
  &lt;/root>

&lt;/configuration></pre>

      <p>This configuration specifies the location of the trust store
         as <em>logging-server-truststore.jks</em> at the root of
         the application's classpath.  You could alternatively 
         specify a <code>file:</code> URL to identify the location of
         the trust store.
      </p>

      <h4>SSL Configuration Properties</h4>
      
      <p>JSSE exposes a large number of configurable options, and 
         Logback's SSL support makes nearly all of them available for
         you to specify in your SSL-enabled component configuration.  
         When using XML configuration, SSL properties are introduced to 
         these components by nesting an &lt;ssl> element in the 
         component configuration.  This configuration element corresponds 
         to the 
         <a href="../xref/ch/qos/logback/core/net/ssl/SSLConfiguration.html">
         <code>SSLConfiguration</code></a> class.
      </p>
      
      <p>When configuring SSL for your components
         you need only configure those SSL properties for which the
         defaults are not adequate.  Overspecifying the SSL configuration
         is often the cause of difficult-to-diagnose problems.
      </p>
 
      <p>The following table describes the top-level SSL configuration
         properties.  Many of these properties introduce additional
         subproperties, which are described in tables that follow 
         after the top-level properties are described.
      </p>
            
      <table class="bodyTable striped">
        <tr>
          <th>Property Name</th>
          <th>Type</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><span class="prop" container="ssl">keyManagerFactory</span></td>
          <td><a href="../xref/ch/qos/logback/core/net/ssl/KeyManagerFactoryFactoryBean.html">
              <code>KeyManagerFactoryFactoryBean</code></a>
          </td>
          <td>Specifies the configuration used to create a
              <a href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/net/ssl/KeyManagerFactory.html">
              <code>KeyManagerFactory</code></a>.  The Java platform's default 
              factory will be used if this property is not configured.  See
              <a href="#KeyManagerFactoryFactoryBean">Key Manager Factory
              Configuration</a>
              below. 
          </td>
        </tr>
        <tr>
          <td><a name="ssl.keyStore"></a><span class="prop" container="ssl">keyStore</span></td>
          <td><a href="../xref/ch/qos/logback/core/net/ssl/KeyStoreFactoryBean.html">
              <code>KeyStoreFactoryBean</code></a>
          </td>
          <td>
            <p>Specifies the configuration used to create a
               <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/security/KeyStore.html">
               <code>KeyStore</code></a>.  The KeyStore created by this property
               should contain a single X.509 credential (consisting of a 
               private key, corresponding certificate, and CA certificate chain).
               This credential is presented by the local SSL peer to the remote
               SSL peer.
            </p>
            <p>When configuring an SSL client (e.g. <code>SSLSocketAppender</code>),
               the <span class="prop" container="ssl">keyStore</span> property
               is needed only if the remote peer is configured to require
               client authentication. 
            </p>
            <p>When configuring an SSL server (e.g. <code>SimpleSSLSocketServer</code>)
               the <span class="prop" container="ssl">keyStore</span> property
               specifies the key store containing the server's credential.  If
               this property is not configured, the JSSE's
               <code>javax.net.ssl.keyStore</code> system property must be
               configured to provide the location of the server's key store.
               See <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#InstallationAndCustomization">
               Customizing JSSE</a> in the 
               <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html">
               JSSE Reference Guide</a> for more information on setting JSSE
               system properties.
            </p>
            <p>See <a href="#KeyStoreFactoryBean">Key Store Configuration</a>
               below. 
            </p>
          </td>
        </tr>
        <tr>
          <td><span class="prop" container="ssl">parameters</span></td>
          <td><a href="../xref/ch/qos/logback/core/net/ssl/SSLParametersConfiguration.html">
              <code>SSLParametersConfiguration</code></a></td>
          <td>Specifies various parameters used in SSL session negotiation.
              See <a href="#SSLParametersConfiguration">SSL Parameters Configuration</a>
              below.
          </td>
        </tr>
        <tr>
          <td><span class="prop" container="ssl">protocol</span></td>
          <td><code>String</code></td>
          <td>Specifies the SSL protocol that will be used to create an 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/net/ssl/SSLContext.html">
              <code>SSLContext</code></a>.
              See the <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#AppA">
              Standard Names</a> specification in the 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html">
              JSSE Reference Guide</a>.  The Java platform's default protocol 
              will be used if this property is not configured.
          </td>
        </tr>
        <tr>
          <td><span class="prop" container="ssl">provider</span></td>
          <td><code>String</code></td>
          <td>Specifies the name of the JSSE provider that will be used to
              create an 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/net/ssl/SSLContext.html">
              <code>SSLContext</code></a>.  The Java platform's default JSSE 
              provider will be used if this property is not configured.
          </td>
        </tr>
        <tr>
          <td><span class="prop" container="ssl">secureRandom</span></td>
          <td><a href="../xref/ch/qos/logback/core/net/ssl/SecureRandomFactoryBean.html">
              <code>SecureRandomFactoryBean</code></a>
          </td>
          <td>Specifies the configuration used to create a
              <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/security/SecureRandom.html">
              <code>SecureRandom</code></a> &mdash; a secure random number
              generator.  The Java platform's default generator will be used  
              if this property is not configured.  See
              <a href="#SecureRandomFactoryBean">Secure Random Generator
              Configuration</a> below. 
          </td>
        </tr>
        <tr>
          <td><span class="prop" container="ssl">trustManagerFactory</span></td>
          <td><a href="../xref/ch/qos/logback/core/net/ssl/TrustManagerFactoryFactoryBean.html">
              <code>TrustManagerFactoryFactoryBean</code></a>
          </td>
          <td>Specifies the configuration used to create a
              <a href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/net/ssl/TrustManagerFactory.html">
              <code>TrustManagerFactory</code></a>.  The Java platform's default 
              factory will be used if this property is not configured.  See
              <a href="#TrustManagerFactoryFactoryBean">Trust Manager Factory</a>
              below. 
          </td>
        </tr>
        <tr>
          <td><a name="ssl.trustStore"></a><span class="prop" container="ssl">trustStore</span></td>
          <td><a href="../xref/ch/qos/logback/core/net/ssl/KeyStoreFactoryBean.html">
              <code>KeyStoreFactoryBean</code></a>
          </td>
          <td>
            <p>Specifies the configuration used to create a
               <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/security/KeyStore.html">
               <code>KeyStore</code></a> used for validating identity of the
               remote SSL peer.  The KeyStore created by this property
               should contain one or more <em>trust anchors</em> &mdash; self-signed
               certificates marked as "trusted" in the keystore.  Typically,
               the trust store contains self-signed CA certificates.  
            </p>
            <p>The trust store specified by this property overrides any trust 
               store specified by the JSSE's <code>javax.net.ssl.trustStore</code> 
               system property and the platform's default trust store.See <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#InstallationAndCustomization">
               Customizing JSSE</a> in the 
               <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html">
               JSSE Reference Guide</a> for more information on setting JSSE
               system properties.
            </p>
          </td>
        </tr>
      </table>
      
      <h4 class="doAnchor"><a name="KeyStoreFactoryBean"></a>
          Key Store Configuration</h4>
          
      <p>The <a href="../xref/ch/qos/logback/core/net/ssl/KeyStoreFactoryBean.html">
         <code>KeyStoreFactoryBean</code></a> specifies the 
         configuration needed to create a 
         <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/security/KeyStore.html">
         <code>KeyStore</code></a> containing X.509 credentials.  The properties
         of this factory bean can be used in the
         <a href="#ssl.keyStore"><span class="prop" container="ssl">keyStore</span></a> 
         and 
         <a href="#ssl.trustStore"><span class="prop" container="ssl">trustStore</span></a>
         properties of the <a href="#SSLConfiguration">SSL Configuration</a>.
      </p>
 
      <table class="bodyTable striped">
        <tr>
          <th>Property Name</th>
          <th>Type</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><span class="prop" container="keyStore">location</span></td>
          <td><code>String</code></td>
          <td>A URL that specifies the location of the key store.  Use
              a <code>file:</code> URL to specify the location of the
              keystore on a filesystem.  Use a <code>classpath:</code>
              URL to specify a keystore than can be found on the classpath.
              If the URL doesn't specify a scheme, <code>classpath:</code>
              is assumed.</td>
        </tr>
        <tr>
          <td><span class="prop" container="keyStore">password</span></td>
          <td><code>String</code></td>
          <td>Specifies the password needed to access the key store.</td>
        </tr>
        <tr>
          <td><span class="prop" container="keyStore">provider</span></td>
          <td><code>String</code></td>
          <td>Specifies the name of the JCA provider that will be used to
              create a <code>KeyStore</code>.  The Java 
              platform's default key store provider will be used if this 
              property is not configured.
          </td>
        </tr>
        <tr>
          <td><span class="prop" container="keyStore">type</span></td>
          <td><code>String</code></td>
          <td>Specifies the <code>KeyStore</code> type.
              See the <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/CryptoSpec.html#AppA">
              Standard Names</a> specification in the 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/CryptoSpec.html">
              Java Cryptography Architecture</a> specification.  The Java 
              platform's default key store type will be used  if this property 
              is not configured.
          </td>
        </tr>
      </table>
      
      <h4><a name="KeyManagerFactoryFactoryBean"></a>
          Key Manager Factory Configuration</h4>
          
      <p>The <a href="../xref/ch/qos/logback/core/net/ssl/KeyManagerFactoryFactoryBean.html">
         <code>KeyManagerFactoryFactoryBean</code></a> specifies the 
         configuration needed to create a 
         <a href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/net/ssl/KeyManagerFactory.html">
         <code>KeyManagerFactory</code></a>.  Generally, it isn't necessary
         to explicitly configure the key manager factory, as the platform's
         default factory is adequate for most needs.
      </p>

      <table class="bodyTable striped">
        <tr>
          <th>Property Name</th>
          <th>Type</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><span class="prop" container="keyManagerFactory">algorithm</span></td>
          <td><code>String</code></td>
          <td>Specifies the <code>KeyManagerFactory</code> algorithm name.
              See the <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#AppA">
              Standard Names</a> specification in the 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html">
              JSSE Reference Guide</a>.  The Java platform's default key 
              manager algorithm will be used if this property is not configured.
          </td>
        </tr>
        <tr>
          <td><span class="prop" container="keyManagerFactory">provider</span></td>
          <td><code>String</code></td>
          <td>Specifies the name of the JCA provider that will be used to
              create a <code>SecureRandom</code> generator.  The Java 
              platform's default JSSE provider will be used if this property 
              is not configured.
          </td>
        </tr>
      </table>

      <h4 class="doAnchor"><a name="SecureRandomFactoryBean"></a>
          Secure Random Generator Configuration</h4>
          
      <p>The <a href="../xref/ch/qos/logback/core/net/ssl/SecureRandomFactoryBean.html">
         <code>SecureRandomFactoryBean</code></a> specifies the 
         configuration needed to create a 
         <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/security/SecureRandom.html">
         <code>SecureRandom</code></a> generator.  Generally, it isn't necessary
         to explicitly configure the secure random generator, as the platform's
         default generator is adequate for most needs.
      </p>
 
      <table class="bodyTable striped">
        <tr>
          <th>Property Name</th>
          <th>Type</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><span class="prop" container="secureRandom">algorithm</span></td>
          <td><code>String</code></td>
          <td>Specifies the <code>SecureRandom</code> algorithm name.
              See the <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/CryptoSpec.html#AppA">
              Standard Names</a> specification in the 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/CryptoSpec.html">
              Java Cryptography Architecture</a> specification.  The Java 
              platform's default random number generation algorithm will be used 
              if this property is not configured.
          </td>
        </tr>
        <tr>
          <td><span class="prop" container="secureRandom">provider</span></td>
          <td><code>String</code></td>
          <td>Specifies the name of the JCA provider that will be used to
              create a <code>SecureRandom</code> generator.  The Java 
              platform's default JSSE provider will be used if this property 
              is not configured.
          </td>
        </tr>
      </table>
      
      <h4><a name="SSLParametersConfiguration"></a>
          SSL Parameters Configuration</h4>
          
      <p>The <a href="../xref/ch/qos/logback/core/net/ssl/SSLParametersConfiguration.html">
         <code>SSLParametersConfiguration</code></a> allows the customization
         of allowed SSL protocols, cipher suites, and client authentication
         options. 
      </p>

      <table class="bodyTable striped">
        <tr>
          <th>Property Name</th>
          <th>Type</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><a name="parameters.excludedCipherSuites"></a>
              <span class="prop" container="parameters">excludedCipherSuites</span></td>
          <td><code>String</code></td>
          <td>
            <p>Specifies a comma-separated list of SSL cipher suite names or
               patterns to disable during session negotiation.  This property is
               used to filter the cipher suites supported by the SSL engine, 
               such that any cipher suite matched by this property is disabled.
            </p>
            <p>Each field in the comma-separated list specified for this 
               property may be a simple string or a regular expression.
            </p>
            <p>See the <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#AppA">
              Standard Names</a> specification in the 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html">
              JSSE Reference Guide</a> for a list of cipher suite names.
            </p>
          </td>
        </tr>
        <tr>
          <td><a name="parameters.includedCipherSuites"></a>
              <span class="prop" container="parameters">includedCipherSuites</span></td>
          <td><code>String</code></td>
          <td>
            <p>Specifies a comma-separated list of SSL cipher suite names or
               patterns to enable during session negotiation.  This property is
               used to filter the cipher suites supported by the SSL engine, 
               such that only those cipher suites matched by this property are 
               enabled.
            </p>
            <p>Each field in the comma-separated list specified for this 
               property may be a simple string or a regular expression.
            </p>
            <p>See the <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#AppA">
              Standard Names</a> specification in the 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html">
              JSSE Reference Guide</a> for a list of cipher suite names.
            </p>
          </td>
        </tr>
        <tr>
          <td><a name="parameters.excludedProtocols"></a>
              <span class="prop" container="parameters">excludedProtocols</span></td>
          <td><code>String</code></td>
          <td>
            <p>Specifies a comma-separated list of SSL protocol names or
               patterns to disable during session negotiation.  This property is
               used to filter the protocols supported by the SSL engine, 
               such that any protocol matched by this property is disabled.
            </p>
            <p>Each field in the comma-separated list specified for this 
               property may be a simple string or a regular expression.
            </p>
            <p>See the <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#AppA">
              Standard Names</a> specification in the 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html">
              JSSE Reference Guide</a> for a list of protocol names.
            </p>
          </td>
        </tr>
        <tr>
          <td><a name="parameters.includedProtocols"></a>
              <span class="prop" container="parameters">includedProtocols</span></td>
          <td><code>String</code></td>
          <td>
            <p>Specifies a comma-separated list of SSL protocol names or
               patterns to enable during session negotiation.  This property is
               used to filter the protocols supported by the SSL engine, 
               such that only those protocols matched by this property are 
               enabled.
            </p>
            <p>Each field in the comma-separated list specified for this 
               property may be a simple string or a regular expression.
            </p>
            <p>See the <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#AppA">
              Standard Names</a> specification in the 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html">
              JSSE Reference Guide</a> for a list of protocol names.
            </p>
          </td>
        </tr>
        <tr>
          <td><a name="parameters.needClientAuth"></a>
              <span class="prop" container="parameters">needClientAuth</span></td>
          <td><code>boolean</code></td>
          <td>Set this property to the value <code>true</code> to 
              configure a server to <em>require</em> a valid client
              certificate.  This property is ignored when configured
              for a client component such as <code>SSLSocketAppender</code>.
          </td>
        </tr>
        <tr>
          <td><a name="parameters.wantClientAuth"></a>
              <span class="prop" container="parameters">wantClientAuth</span></td>
          <td><code>boolean</code></td>
          <td>Set this property to the value <code>true</code> to 
              configure the server to <em>request</em> a client
              certificate.  This property is ignored when configured
              for a client component such as <code>SSLSocketAppender</code>.
          </td>
        </tr>
      </table>
      
      <h4><a name="TrustManagerFactoryFactoryBean"></a>
          Trust Manager Factory Configuration</h4>
          
      <p>The <a href="../xref/ch/qos/logback/core/net/ssl/TrustManagerFactoryFactoryBean.html">
         <code>TrustManagerFactoryFactoryBean</code></a> specifies the 
         configuration needed to create a 
         <a href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/net/ssl/TrustManagerFactory.html">
         <code>TrustManagerFactory</code></a>.  Generally, it isn't necessary
         to explicitly configure the trust manager factory, as the platform's
         default factory is adequate for most needs.
      </p>

      <table class="bodyTable striped">
        <tr>
          <th>Property Name</th>
          <th>Type</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><span class="prop" container="trustManagerFactory">algorithm</span></td>
          <td><code>String</code></td>
          <td>Specifies the <code>TrustManagerFactory</code> algorithm name.
              See the <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#AppA">
              Standard Names</a> specification in the 
              <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html">
              JSSE Reference Guide</a>.  The Java platform's default key 
              manager algorithm will be used if this property is not configured.
          </td>
        </tr>
        <tr>
          <td><span class="prop" container="trustManagerFactory">provider</span></td>
          <td><code>String</code></td>
          <td>Specifies the name of the JCA provider that will be used to
              create a <code>SecureRandom</code> generator.  The Java 
              platform's default JSSE provider will be used if this property 
              is not configured.
          </td>
        </tr>
      </table>
      
      <h2 class="doAnchor"><a name="Examples"></a>Examples</h2>

      <h3>Using JSSE System Properties</h3>
      <p>JSSE system properties can be used to specify the location and 
      password for a key store containing your server's X.509 credential,
      or to specify the location and password for a trust store 
      containing self-signed root CA certificates used by your client
      components to validate server trust.</p>

      <h4>Specifying the Server's Key Store</h4>
      <p>When running a server component, you need to specify the location
      and password for the key store containing the server's credential.
      One way to do this is using JSSE system properties.  The following
      example shows a command line that could be used to start the
      <code>SimpleSSLSocketServer</code> that is shipped with Logback.</p>
    
      <p class="source">java -DkeyStore=/etc/logback-server-keystore.jks \
     -DkeyStorePassword=changeit -DkeyStoreType=JKS \
     ch.qos.logback.net.SimpleSSLSocketServer 6000 /etc/logback-server-config.xml</p>
              
      <p>Note that when using the JSSE <em>keyStore</em> system property,
      a path to the key store is specified.  When specifying the location
      in <em>logback.xml</em>, a URL for the key store is specified.</p>
      
      <p>While this example starts the standalone server application
      provided with Logback, the same system properties could be specified
      to start any application that uses an SSL-enabled Logback server
      component.
      
      <h4>Specifying the Client's Trust Store</h4>
      
      <p>When using a client component, you need to specify the location
      and password for a trust store containing root CA certificates used
      for validating server trust.  One way to do this is using JSSE
      system properties.  The following example shows a command line
      that could be used to start an application named 
      <code>com.example.MyLoggingApplication</code> that uses one or
      more of Logback's SSL-enabled client components.</p>

      <p class="source">java -DtrustStore=/etc/logback-client-truststore.jks \
     -DtrustStorePassword=changeit -DtrustStoreType=JKS \
     com.example.MyLoggingApplication</p>
      
      <p>Note that when using the JSSE <em>trustStore</em> system property,
      a path to the key store is specified.  When specifying the location
      in <em>logback.xml</em>, a URL for the trust store is specified.</p>
      
      <h3>Creating and Using a Self-Signed Server Component Credential</h3>
      <p>To generate a self-signed certificate, you can use the <em>keytool</em>
      utility that is shipped with the Java Runtime Environment (JRE).
      The instructions below walk through the process of creating a
      self-signed X.509 credential in a key store for your server 
      component and creating a trust store for use with your client
      components.
      </p>
      
      <h4>Creating the server component credential:</h4>
      <p>The following command will generate the self-signed client
      credential in a file named <em>server.keystore</em>.</p>
      <pre class="source">keytool -genkey -alias server -dname &quot;CN=my-logging-server&quot; \
    -keyalg RSA -validity 365 -keystore server.keystore
Enter keystore password: &lt;Enter password of your choosing>
Re-enter new password: &lt;Re-enter same password>
Enter key password for &lt;my-logging-server>
	(RETURN if same as keystore password):  &lt;Press RETURN>
</pre>

      <p>The name <em>my-logging-server</em> used in the <em>dname</em>
      may be any valid name of your choosing.  You may wish to use the
      fully-qualified domain name of the server host. The
      <em>validity</em> argument specifies the number of calendar days
      from the present date until the credential expires.</p>
      
      <p>In production settings, it is especially important to choose a
      strong password for the key store containing your server credential.
      This password protects the server's private key, preventing it
      from being used by an authorized party.  Make note of the
      password, because you will need it in subsequent steps and when
      configuring your server.
      </p>

      <h4>Creating a trust store for client components:</h4>
      <p>For use in the configuration of your client components, the 
      server's certificate needs to be exported from the key store
      created in the previous step, and imported into a trust store.  The
      following commands will export the certificate and import it into
      a trust store named <em>server.truststore</em>.</p>
      
      <pre class="source">keytool -export -rfc -alias server -keystore server.keystore \
    -file server.crt
Enter keystore password: &lt;Enter password you chose for in previous step>

keytool -import -alias server -file server.crt -keystore server.truststore
Enter keystore password: &lt;Enter password of your choosing>
Re-enter new password: &lt;Re-enter same password>
Owner: CN=my-logging-server
Issuer: CN=my-logging-server
Serial number: 6e7eea40
Valid from: Sun Mar 31 07:57:29 EDT 2013 until: Mon Mar 31 07:57:29 EDT 2014

   ...

Trust this certificate? [no]:  &lt;Enter "yes">
</pre>

      <p>The first command exports the server's certificate (but not the
      server's private key) from the key store and into a file named
      <em>server.crt</em>.  The second step creates a new trust store
      named <em>server.truststore</em> containing the server certificate.
      </p>
      
      <p>In production settings, it is especially important to choose a
      strong password for the trust store that is different from the 
      password you chose of the server key store.  Make note of this
      password, because you will need it when configuring your appender
      clients.
      </p>
          
      <h4>Configuring the server component:</h4>
      <p>You will need to copy the <em>server.keystore</em> file into your 
      server application's configuration.  The key store can be placed
      with your application's classpath resources, or it may simply be
      placed somewhere on the server host's filesystem.  When specifying
      the location of the key store in the configuration, you will use
      either a <code>classpath:</code> URL or <code>file:</code> URL, as
      appropriate.  A example server configuration follows:</p>

      <p class="example">Example: Server Component Configuration</p>
      <pre class="prettyprint source">&lt;configuration debug="true">
  &lt;appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    &lt;encoder>
      &lt;pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n&lt;/pattern>
    &lt;/encoder>
  &lt;/appender>
  
  &lt;root level="DEBUG">
    &lt;appender-ref ref="CONSOLE" />
  &lt;/root>

  &lt;server class="ch.qos.logback.classic.net.server.SSLServerSocketReceiver">
    &lt;ssl>
      &lt;keyStore>
        &lt;location>classpath:server.keystore&lt;/location>
        &lt;password>${server.keystore.password}&lt;/password>
      &lt;/keyStore>
    &lt;/ssl>
  &lt;/server>
&lt;/configuration></pre>
      
      <p>This example assumes that the key store is located at the root
      of the application's classpath.</p>
      
      <p>Note that this configuration specifies the key store password
      using the <em>server.keystore.password</em> substitution variable.
      This approach would allow you to avoid storing the password in
      any configuration file.  For example, your application could
      prompt for this password on the console at startup, and then 
      set the <em>server.keystore.password</em> as a system property 
      using the entered password before configuring the logging system.
      </p>
      
      <h4>Configuring client components:</h4>
      <p>You will need to copy the <em>server.truststore</em> file into
      the application configuration of each application that uses an
      SSL-enabled component acting in the client mode.  The trust store 
      can be placed with your application's classpath resources, or it
      may simply be placed somewhere on the filesystem.  When specifying 
      the location of the trust store in the configuration, you will use 
      either a <code>classpath:</code> URL or <code>file:</code> URL, as
      appropriate.  A example appender client configuration follows:</p>

      <p class="example">Example: Appender Client Configuration</p>

      <pre class="prettyprint source">&lt;configuration debug="true">
  &lt;appender name="SOCKET" class="ch.qos.logback.classic.net.SSLSocketAppender">
    &lt;remoteHost>${host}&lt;/remoteHost>
    &lt;ssl>
      &lt;trustStore>
        &lt;location>classpath:server.truststore&lt;/location>
        &lt;password>${server.truststore.password}&lt;/password>
      &lt;/trustStore>
    &lt;/ssl>
  &lt;/appender>

  &lt;root level="DEBUG">
    &lt;appender-ref ref="SOCKET" />
  &lt;/root>
&lt;/configuration></pre>

      <p>This example assumes that the trust store is located at the root
      of the application's classpath.</p>
      
      <p>Note that this configuration specifies the trust store password
      using the <em>server.truststore.password</em> substitution variable.
      This approach would allow you to avoid storing the password in
      any configuration file.  For example, your application could
      prompt for this password on the console at startup, and then 
      set the <em>server.truststore.password</em> as a system property 
      using the entered password before configuring the logging system.
      </p>

      <h2>Auditing the SSL Configuration</h2>
      <p>In settings where secure communications are required, it is often
      necessary to audit the configuration of components that use SSL to
      validate conformance with local security policies.  The SSL
      support in Logback addresses this need by providing detailed
      logging of SSL configuration when Logback is initialized.  You can 
      enable audit logging using the <code>debug</code> property in the
      configuration:</p>
      
      <pre class="prettyprint source">&lt;configuration debug="true">
  
  ...
  
&lt;/configuration></pre>

      <p>With the debug property enabled, all of the relevant aspects of
      the resulting SSL configuration will be logged when the logging
      system is initialized.  A representative example of the information
      logged for SSL follows.</p>
      
      <p class="example">Example: SSL Configuration Audit Logging</p>
      
      <pre>06:46:31,941 |-INFO in SSLServerSocketReceiver@4ef18d37 - SSL protocol 'SSL' provider 'SunJSSE version 1.6'
06:46:31,967 |-INFO in SSLServerSocketReceiver@4ef18d37 - key store of type 'JKS' provider 'SUN version 1.6': file:src/main/java/chapters/appenders/socket/ssl/keystore.jks
06:46:31,967 |-INFO in SSLServerSocketReceiver@4ef18d37 - key manager algorithm 'SunX509' provider 'SunJSSE version 1.6'
06:46:31,973 |-INFO in SSLServerSocketReceiver@4ef18d37 - secure random algorithm 'SHA1PRNG' provider 'SUN version 1.6'
06:46:32,755 |-INFO in SSLParametersConfiguration@4a6f19d5 - enabled protocol: SSLv2Hello
06:46:32,755 |-INFO in SSLParametersConfiguration@4a6f19d5 - enabled protocol: SSLv3
06:46:32,755 |-INFO in SSLParametersConfiguration@4a6f19d5 - enabled protocol: TLSv1
06:46:32,756 |-INFO in SSLParametersConfiguration@4a6f19d5 - enabled cipher suite: SSL_RSA_WITH_RC4_128_MD5
06:46:32,756 |-INFO in SSLParametersConfiguration@4a6f19d5 - enabled cipher suite: SSL_RSA_WITH_RC4_128_SHA
06:46:32,756 |-INFO in SSLParametersConfiguration@4a6f19d5 - enabled cipher suite: TLS_RSA_WITH_AES_256_CBC_SHA
</pre>

      <p>The output shown here has been truncated for brevity's sake, 
      but would typically include the complete list of protocols, 
      providers, algorithms, and cipher suites, as well as the location
      of key store and trust store resources utilized in the configuration.
      </p>
      
      <p>While none of this audit logging is particularly sensitive,
      best practices for security would suggest that this logging should
      not remain enabled in production settings after the configuration
      has been validated.  Audit logging is disabled when the 
      <code>debug</code> property is removed or set to <code>false</code>.
      </p>
      
      <h2>Resolving SSL Exceptions</h2>
      <p>When SSL is misconfigured, it generally results in the client
         and server components being unable to negotiate an agreeable 
         session.  This problem usually manifests itself as exceptions 
         being thrown by both parties when the client attempts to connect 
         to the server.
      </p>
      <p>The content of the exception messages varies depending on whether 
         you are looking at the client's log or the server's log.  This
         is mostly due to inherent protocol limitations in error reporting
         during session negotiation.  As a consequence of this fact,
         in order to troubleshoot session negotiation problems, you will
         usually want to look at the logs of both the client and the
         server.
      </p>
      
      <h3>Server's Certificate is Not Available</h3>
      <p>When starting the server component, you
         see the following exception in the log:</p>
         
      <p><em>javax.net.ssl.SSLException: No available certificate or 
         key corresponds to the SSL cipher suites which are enabled</em>
      </p>
      
      <p>In most cases this means that you have not configured 
         the location of the key store containing the server's private 
         key and corresponding certificate.
      </p>
      
      <h4>Solution</h4>
      <p>Using either the 
         <a href="#basicConfig.keyStore">Key Store system
         properties</a> or the <a href="#ssl.keyStore">
         <span class="prop">keyStore</span></a> property of the 
         server component's <span class="prop">ssl</span> property, 
         you must specify the location and password for the key store 
         containing the server's private key and certificate.
      </p>
      
      <h3>Client Does Not Trust the Server</h3>
      <p>When the client attempts to connect to the server, you see the 
      following exception in the log:</p>
      
      <p><em>javax.net.ssl.SSLHandshakeException: 
              sun.security.validator.ValidatorException: 
              PKIX path building failed</em>
      </p>
      <p>This problem is the result of the server presenting a certificate
         the client does not trust.  The most common cause is that you 
         are using a self-signed server certificate (or a server 
         certificate that was signed by your organization's internal
         certification authority) and you have not configured the client
         so that it references a trust store containing the server's 
         self-signed certificate (or the trusted root certificate(s) for 
         the CA that signed your server certificate).         
      </p> 
      <p>This problem can also occur if your server certificate has
         expired or has been revoked.  If you have access to the server
         log you will likely see the following exception logged
         each time the client attempts to connect:
      </p>
      
      <p><em>javax.net.ssl.SSLHandshakeException: Received fatal alert: ...</em>
      </p>
      
      <p>The remainder of the exception message will usually provide a
         code that indicates why the client rejected the server's
         certificate.
      </p>
      <table class="bodyTable striped">
        <tr>
          <th>Code</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><code>certificate_unknown</code></td>
          <td>Usually indicates that the client's trust store has not
              been properly configured.
          </td>
        </tr>
        <tr>
          <td><code>certificate_expired</code></td>
          <td>Indicates that the server's certificate has expired and
              needs to be replaced.
          </td>
        </tr>
        <tr>
          <td><code>certificate_revoked</code></td>
          <td>Indicates that the issuing certification authority (CA)
              has revoked the server's certificate and the certificate
              needs to be replaced.
          </td>
        </tr>
      </table>
        
      <h4>Solutions</h4>
      <p>If the server's log message is reporting <code>certificate_unknown</code>
         then using either the <a href="#basicConfig.trustStore">Trust Store system
         properties</a> or the <a href="#ssl.trustStore">
         <span class="prop">trustStore</span></a> property of the 
         appender component's <span class="prop">ssl</span> property, 
         you must specify the location and password for the trust 
         store containing the server's self-signed certificate or
         the issuing certificate authority's root certificate.
      </p>

      <p>If the server's log message is reporting 
         <code>certificate_expired</code> or <code>certificate_revoked</code> 
         the server needs a new certificate.  The new certificate 
         and associated private key needs to be placed in the key store 
         specified in the server's configuration.  And, if using 
         a self-signed server certificate, the server's certificate also
         needs to be placed in the trust store specified in the appender
         client's configuration.
      </p>
      
      <h3>Server Does Not Trust the Client</h3>
      <p>NOTE: <strong>This problem can occur only if you have explicitly 
         configured the server to request a client certificate (using 
         either the <a href="#parameters.needClientAuth"><span class="prop">needClientAuth</span></a> or 
         <a href="#parameters.wantClientAuth"><span class="prop">wantClientAuth</span></a>
         property)</strong>.
      </p>
 
      <p>When the client attempts to connect to the logging
         server, you see the following exception in the client's log:
      </p>
      
      <p><em>javax.net.ssl.SSLHandshakeException:  Received fatal 
         alert: ...</em>
      </p>

      <p>The remainder of the exception message will usually provide a
         code that indicates why the server rejected the client's
         certificate.
      </p>
      <table class="bodyTable striped">
        <tr>
          <th>Code</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><code>certificate_unknown</code></td>
          <td>Usually indicates that the server's trust store has not
              been properly configured.
          </td>
        </tr>
        <tr>
          <td><code>certificate_expired</code></td>
          <td>Indicates that the client's certificate has expired and
              needs to be replaced.
          </td>
        </tr>
        <tr>
          <td><code>certificate_revoked</code></td>
          <td>Indicates that the issuing certification authority (CA)
              has revoked the client's certificate and the certificate
              needs to be replaced.
          </td>
        </tr>
      </table>
        
      <h4>Solutions</h4>
      <p>If the client's log message is reporting <code>bad_certificate</code>
         then using either the <a href="#basicConfig.trustStore">Trust Store system
         properties</a> or the <a href="#ssl.trustStore">
         <span class="prop">trustStore</span></a> property of the 
         server component's <span class="prop">ssl</span> property, 
         you must specify the location and password for the trust 
         store containing the client's self-signed certificate or
         the issuing certificate authority's root certificate.
      </p>

      <p>If the server's log message is reporting 
         <code>certificate_expired</code> or <code>certificate_revoked</code> 
         the client needs a new certificate.  The new certificate 
         and associated private key needs to be placed in the key store 
         specified in the client's configuration.  And, if using 
         a self-signed client certificate, the client's certificate also
         needs to be placed in the trust store specified in the 
         servers's configuration.
      </p>
      
      <h3>Client and Server Cannot Agree on a Protocol</h3>
      <p>NOTE: <strong>This problem usually occurs only when you are
         explicitly 
         <a href="#parameters.excludedProtocols">excluding</a> or 
         <a href="#parameters.includedProtocols">including</a> SSL 
         protocols in your configuration</strong>.
      </p>

      <p>When the client attempts to connect to the server, you see 
         the following exception in the log:</p>
      
      <p><em>javax.net.ssl.SSLHandshakeException:  Received fatal 
         alert: handshake_failure</em>
      </p>
      
      <p>The server's log message is usually more descriptive.  For
         example:</p>
      
      <p><em>javax.net.ssl.SSLHandshakeException: SSLv2Hello is disabled</em>
      </p>
      
      <p>Generally, this means that you have excluded a protocol from
         one of the peers and not the other.</p>
         
      <h4>Solution</h4>
      <p>Check the values specified for the 
         <a href="#parameters.excludedProtocols"><span class="prop">excludedProtocols</span></a> and
         <a href="#parameters.includedProtocols"><span class="prop">includedProtocols</span></a>
         properties on both the server and client.
      </p>

      <h3>Client and Server Cannot Agree on a Cipher Suite</h3>
      <p>NOTE: <strong>This problem usually occurs only when you are
         explicitly 
         <a href="#parameters.excludedCipherSuites">excluding</a> or
         <a href="#parameters.includedCipherSuites">including</a> SSL
         cipher suites in your configuration</strong>.
      </p>
      
      <p>When the client attempts to connect to the
         server, you see the following exception in the log:
      </p>
      
      <p><em>javax.net.ssl.SSLHandshakeException:  Received fatal 
         alert: handshake_failure</em>
      </p>
      
      <p>The server's log message is usually more descriptive:
      </p>
      
      <p><em>javax.net.ssl.SSLHandshakeException: no cipher suites in common</em>
      </p>
      
      <p>This means that you have configured the cipher suites on the
         server and client such that the intersection
         of their respective sets of enabled cipher suites is empty.</p>
      
      <h4>Solution</h4>
      <p>Check the values specified for the 
         <a href="#parameters.excludedCipherSuites"><span class="prop">excludedCipherSuites</span></a> and
         <a href="#parameters.includedCipherSuites"><span class="prop">includedCipherSuites</span></a>
         properties on both the server and client.
      </p>
         
      <script src="../templates/footer.js" type="text/javascript"></script>

    </div>
  </body>
</html>